home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / KSLIB11.ARJ / FUNCLIST.DOC < prev    next >
Text File  |  1991-11-13  |  81KB  |  2,788 lines

  1. Function        CFcolcvt
  2. Prototype in    cf.h
  3. Module            cf
  4. Library            tll
  5.  
  6. int        CFcolcvt(char *s)
  7.  
  8. Converts a character string into it's corresponding colour number.
  9.  
  10. Parameters
  11.     s        The string to convert.
  12.  
  13. Returns
  14.     The number of the color the string describes, or -1 if the string
  15.     could not be matched against one of the known colours.
  16.  
  17. -------------------------------------------------------------------------------
  18. Function        CFcolor
  19. Prototype in    cf.h
  20. Module            cf
  21. Library            tll
  22.  
  23. char    *CFcolor(int c)
  24.  
  25. Returns the string corresponding to the specified colour number.
  26.  
  27. Parameters
  28.     c        The number of the colour.
  29.  
  30. Returns
  31.     A pointer to the character string describing the colour, or NULL
  32.     if the colour is out of range.
  33.  
  34. -------------------------------------------------------------------------------
  35. Function        CFcolval
  36. Prototype in    cf.h
  37. Module            cf
  38. Library            tll
  39.  
  40. int        CFcolval(char *s)
  41.  
  42. Converts a string of the form :
  43.  
  44. foreground,background
  45.  
  46. into the corresponding integer value for use when setting the screen
  47. colour. Two locally declared static variables are used to hold the
  48. colour once determined. These are initially set to white on black.
  49. If either part of the string is missing, the corresponding part of the
  50. colour is left unchanged. Thus, the following commands, if executed
  51. consecutively from the start of a program, would change the screen
  52. colours as follows :
  53.  
  54. Command                        Screen colour after executing
  55. --------------------        -----------------------------
  56. At start of program            white on black
  57. CFcolval("green,brown");    green on brown
  58. CFcolval("blue");            blue on brown
  59. CFcolval(",white");            blue on white
  60.  
  61. Parameters
  62.     s        The string to convert
  63.  
  64. Returns
  65.     The integer corresponding to the new screen colours.    
  66.  
  67. -------------------------------------------------------------------------------
  68. Function        CFconf
  69. Prototype in    cf.h
  70. Module            cf
  71. Library            tll
  72.  
  73. int        CFconf(char *f,CFdata *d)
  74.  
  75. Read the specified config file into the specified variables. CFopen is
  76. called to open the config file as normal, then CFread is repeatedly
  77. called to read in the file. Each valid assignment statement is checked
  78. against the list of items parsed, and if a match is found, that variable
  79. is updated. Any invalid assignment statements are ignored.
  80.  
  81. Parameters :
  82.     f        The name of the config file as per CFopen.
  83.     d        Pointer to a list of valid assignment commands. Each item
  84.             contains a character string and a pointer to the variable to
  85.             hold that value. The character string holds the variable type
  86.             in the first character position, and the <cmd> in the rest.
  87.             Valid types are :    S : String value  (xxxxx)
  88.                                 C : Color value   (foreground,background)
  89.                                 I : Integer value (nnn)
  90.                                 L : Long value    (nnn)
  91.                                 F : Float value   (nnn.nn)
  92.                                 D : Double value  (nnn.nn)
  93.  
  94. Return values :
  95.      0        All ok.
  96.     -1        File not found.
  97.     -2        Syntax error.
  98.     -3        Command not found.
  99.  
  100. -------------------------------------------------------------------------------
  101. Function        CFinit
  102. Prototype in    cf.h
  103. Module            cf
  104. Library            tll
  105.  
  106. void    CFinit(void)
  107.  
  108. Initialises the CF routines. Does not need to be called by the programmer
  109. as all the CF routines check for initialisation at their start.
  110.  
  111. Parameters
  112.     none
  113.  
  114. Returns
  115.     nothing
  116.  
  117. -------------------------------------------------------------------------------
  118. Function        CFopen
  119. Prototype in    cf.h
  120. Module            cf
  121. Library            tll
  122.  
  123. int        CFopen(char *s)
  124.  
  125. Open a configuration file for later use by CFread.
  126.  
  127. Parameters :
  128.     s        Full pathname of config file. If <s> is NULL or empty, a file
  129.             with the program's name and ".cfg" extension is looked for,
  130.             first in the current directory, then the home directory. If <s>
  131.             is specified, only <s> is looked for.
  132.  
  133. Return Values :
  134.     0        Config file not found in any of the three locations.
  135.     1        User supplied filename found.
  136.     2        Found in current directory.
  137.     3        Found in home directory.
  138.  
  139. -------------------------------------------------------------------------------
  140. Function        CFread
  141. Prototype in    cf.h
  142. Module            cf
  143. Library            tll
  144.  
  145. int        CFread(char *cmd,char *arg)
  146.  
  147. Read the next assignment statement from the config file (if open). If no
  148. config file is currently open, return -1 (EOF). If an invalid statement is
  149. encountered (positive return value), <cmd> will hold the entire line
  150. containing the error, and <arg> will be empty. A maximum line size in the
  151. config file of 80 characters is enforced (anything past this is truncated
  152. internally). Thus, <cmd> and <arg> only need to be able to hold 81 chars.
  153. An assignment statement is of the form
  154.  
  155. [<cmd> = <arg>] [#<comment>]
  156.  
  157. Note that all white space is ignored, empty lines and lines containing only
  158. comments are valid, and anything after the first '#' on a line is treated
  159. as a comment. <cmd> may only consist of alphanumeric characters, while
  160. <arg> may consist of any character except '#'. As with <cmd>, all
  161. whitespace is generally ignored when scanning <arg>, unless it is enclosed
  162. in double quotes. Likewise, the '#' character may be included as part of
  163. <arg> if it is enclosed in double quotes.
  164.  
  165. Parameters :
  166.     cmd        Pointer to a character array at least 81 characters long. It
  167.             will hold the parameter name on return.
  168.     arg        Pointer to a character array at least 81 characters long. It
  169.             will hold the parameter value on return.
  170.  
  171. Return Values :
  172.     -1        No more assignment statements available for reading from file.
  173.      0        Valid (cmd,arg) pair has been found.
  174.      1        Invalid characters found in the parameter name.
  175.      2        Syntax error in assignment statement.
  176.  
  177. -------------------------------------------------------------------------------
  178. Function        CFwrite
  179. Prototype in    cf.h
  180. Module            cf
  181. Library            tll
  182.  
  183. int        CFwrite(char *f,CFdata *d)
  184.  
  185. The inverse of the CFread function. Opens the specified file, and
  186. writes the contents of the specified CFdata structure to the file.
  187.  
  188. Parameters
  189.     f        The file to write to.
  190.     d        The data structure to write.
  191.  
  192. Returns
  193.     Zero if the write operation was successful, or -1 if it wasn't.
  194.  
  195. -------------------------------------------------------------------------------
  196. Function        DBadd
  197. Prototype in    db.h
  198. Module            db
  199. Library            dbl
  200.  
  201. int        DBadd(void *r)
  202.  
  203. Adds the specified record to the currently active database file.
  204.  
  205. Parameters
  206.     r        A pointer to the record to be added.
  207.  
  208. Returns
  209.     The record number at which the record was added if the operation was
  210.     successful, or -1 if it wasn't.
  211.  
  212. -------------------------------------------------------------------------------
  213. Function        DBbot
  214. Prototype in    db.h
  215. Module            db
  216. Library            dbl
  217.  
  218. int        DBbot(void)
  219.  
  220. Returns the record number of the last record in the currently active
  221. database file.
  222.  
  223. Parameters
  224.     None
  225.  
  226. Returns
  227.     The last record number if there is a currently active database file,
  228.     or -1 if there isn't.
  229.  
  230. -------------------------------------------------------------------------------
  231. Function        DBclose
  232. Prototype in    db.h
  233. Module            db
  234. Library            dbl
  235.  
  236. DBfile    *DBclose(void)
  237.  
  238. This function closes the currently active database file, together with
  239. it's index file. The new active database will be the last opened one.
  240. If no other databases are open, there will be no active database.
  241.  
  242. Parameters
  243.     none
  244.  
  245. Returns
  246.     A pointer to the new active database, or NULL if there are no more
  247.     databases open.
  248.  
  249. -------------------------------------------------------------------------------
  250. Function        DBcmp
  251. Prototype in    db.h
  252. Module            db
  253. Library            dbl
  254.  
  255. int        DBcmp(void *rs,void *rd)
  256.  
  257. Compares two areas of memory. The number of bytes compared is the
  258. record size of the currently active database. The comparison returns
  259. a value less than zero if the first area is less than the second, zero
  260. if they are equal, or greater than zero if the first area is greater than
  261. the second
  262.  
  263. Parameters
  264.     rs        A pointer to the first area of memory.
  265.     rd        A pointer to the second area of memory.
  266.  
  267.     Returns
  268.         The result of the comparison, or zero if there is no currently
  269.         active database.
  270.  
  271. -------------------------------------------------------------------------------
  272. Function        DBcopy
  273. Prototype in    db.h
  274. Module            db
  275. Library            dbl
  276.  
  277. int        DBcopy(void *rs,void *rd)
  278.  
  279. Copies one area of memory to another. The number of bytes copied is
  280. the record size of the currently active database.
  281.  
  282. Parameters
  283.     rs        A pointer to the area of memory to copy from.
  284.     rd        A pointer to the area of memory to copy to.
  285.  
  286. Returns
  287.     The record size of the currently active database if there is one,
  288.     or zero if there isn't.
  289.  
  290. -------------------------------------------------------------------------------
  291. Function        DBdelete
  292. Prototype in    db.h
  293. Module            db
  294. Library            dbl
  295.  
  296. int        DBdelete(void)
  297.  
  298. Deletes the record at the current record indicator in the currently active
  299. database file.
  300.  
  301. Parameters
  302.     none
  303.  
  304. Returns
  305.     -1 in all cases.
  306.  
  307. -------------------------------------------------------------------------------
  308. Function        DBend
  309. Prototype in    db.h
  310. Module            db
  311. Library            dbl
  312.  
  313. void    DBend(void)
  314.  
  315. Should not be called by the application. This function is called via
  316. an 'atexit' call originated in DBopen. It closes all database and index
  317. files in an orderly manner.
  318.  
  319. Parameters
  320.     none
  321.  
  322. Returns
  323.     nothing
  324.  
  325. -------------------------------------------------------------------------------
  326. Function        DBfindfirst
  327. Prototype in    db.h
  328. Module            db
  329. Library            dbl
  330.  
  331. int        DBfindfirst(void *r)
  332.  
  333. Finds the first record in the currently active database which matches
  334. the specified memory area.
  335.  
  336. Parameters
  337.     r        A pointer to the memory area to find.
  338.  
  339. Returns
  340.     The record number it was found at, if it was, or -1 if either there
  341.     is no currently active database, or the record was not found.
  342.  
  343. -------------------------------------------------------------------------------
  344. Function        DBfindnext
  345. Prototype in    db.h
  346. Module            db
  347. Library            dbl
  348.  
  349. int        DBfindnext(void *r)
  350.  
  351. Finds the next record in the currently active database which matches the
  352. specified memory area. The search begins at the record succeeding the
  353. current record. Generally used after DBfindfirst, but may be used at any
  354. time.
  355.  
  356. Parameters
  357.     r        A pointer to the memory area to find.
  358.  
  359. Returns
  360.     The record number it was found at, if it was, or -1 if either there
  361.     is no currently active database, or the record was not found.
  362.  
  363. -------------------------------------------------------------------------------
  364. Function        DBgo
  365. Prototype in    db.h
  366. Module            db
  367. Library            dbl
  368.  
  369. int        DBgo(int r)
  370.  
  371. Moves the current record indicator to the specified record in the
  372. currently active database.
  373.  
  374. Parameters
  375.     r        The record number to move to. Range from 0 to the number of
  376.             database records - 1.
  377.  
  378. Returns
  379.     The new current record number if the move was successful, or -1 if
  380.     it wasn't. If the specified record was out of range, the current
  381.     record indicator will point to the requested record anyway, which
  382.     other functions will treat as either before the top, or after the
  383.     bottom, of the file, depending on whether the requested record was
  384.     less than zero, or greater than that allowed, respectively.
  385.  
  386. -------------------------------------------------------------------------------
  387. Function        DBiread
  388. Prototype in    db.h
  389. Module            db
  390. Library            dbl
  391.  
  392. int        DBiread(int n)
  393.  
  394. Should not be called by the application program.
  395. Reads an index record and returns the database record number it points
  396. to.
  397.  
  398. Parameters:
  399.     n        Index record number to read. Range from 0 to the number of
  400.             index records - 1.
  401.  
  402. Returns
  403.     The database record number (from 0 to the number of database records
  404.     - 1) if the index record number was valid, or -1 if it wasn't.
  405.  
  406. -------------------------------------------------------------------------------
  407. Function        DBiwrite
  408. Prototype in    db.h
  409. Module            db
  410. Library            dbl
  411.  
  412. int        DBiwrite(int n,int datarec)
  413.  
  414. Should not be called by the application program.
  415. Writes a value into the specified index record.
  416.  
  417. Parameters
  418.     n        The index record to write to. Range from zero to the number
  419.             of index records in the file. If it equals the number of
  420.             index records, it implies an addition to the end of the index
  421.             file
  422.     datarec    The value to write. Normally points to a record in the
  423.             database file, but may theoretically hold any value.
  424.  
  425. Returns
  426.     TRUE if the write was successful, or FALSE if it wasn't.
  427.  
  428. -------------------------------------------------------------------------------
  429. Function        DBopen
  430. Prototype in    db.h
  431. Module            db
  432. Library            dbl
  433.  
  434. DBfile    *DBopen(char *fn,int rs,char *ifn,int (*func)(void *,void *))
  435.  
  436. Opens the specified database file and prepares it for access
  437. according to the specified index file and function.
  438.  
  439. Parameters
  440.     fn        Pathname of the database file.
  441.     rs        Size of each record in the database file in bytes.
  442.     ifn        Pathname of the index file.
  443.     func    Comparison function.
  444.  
  445. Returns
  446.     A pointer to the DBfile structure (defined in db.h) for this
  447.     database, or NULL if the open failed.
  448.  
  449. -------------------------------------------------------------------------------
  450. Function        DBread
  451. Prototype in    db.h
  452. Module            db
  453. Library            dbl
  454.  
  455. int        DBread(void *r)
  456.  
  457. Reads the current record from the active database into the memory area
  458. pointed to by 'r'.
  459.  
  460. Parameters
  461.     r        A pointer to the memory area to hold the file data.
  462.  
  463. Returns
  464.     The current record number if the read was successful, or -1 if it
  465.     wasn't.
  466.  
  467. -------------------------------------------------------------------------------
  468. Function        DBreadn
  469. Prototype in    db.h
  470. Module            db
  471. Library            dbl
  472.  
  473. int        DBreadn(int rn,void *r)
  474.  
  475. Reads the specified record from the currently active database file into
  476. the specified memory area.
  477.  
  478. Parameters
  479.     rn        The record number to read.
  480.     r        A pointer to the memory area to read into.
  481.  
  482. Returns
  483.     The record number read if successful, or -1 if not.
  484.  
  485. -------------------------------------------------------------------------------
  486. Function        DBrecno
  487. Prototype in    db.h
  488. Module            db
  489. Library            dbl
  490.  
  491. int        DBrecno(void)
  492.  
  493. Returns the current record number in the currently active database.
  494.  
  495. Parameters
  496.     none
  497.  
  498. Returns
  499.     The record number if there is a currently active database, or -1 if
  500.     there isn't.
  501.  
  502. -------------------------------------------------------------------------------
  503. Function        DBseekfirst
  504. Prototype in    db.h
  505. Module            db
  506. Library            dbl
  507.  
  508. int        DBseekfirst(void *r,int (*func)(void *,void *))
  509.  
  510. This function and DBseeknext are the same as findfirst and findnext,
  511. except the programmer must supply the comparison function. This comparison
  512. function must be a less exact (or as exact) version of the index function.
  513. For instance, if the index function was based on a string comparison of all
  514. characters in the surname, this function could be based on a string
  515. comparison of part of the surname, but could not be based on a comparison
  516. of the surname and the first name combined.
  517.  
  518. An example...
  519. In an application program I've written, part of the database record is the
  520. patient's surname. This field is also the sorting key for the database.
  521. Thus, my index function compares the surname's, looking for an *exact*
  522. match. However, the program allows the user to scan a list of all patients
  523. matching a given template. The user types in the first few characters of
  524. a surname, and a list is brought up showing all patients with surnames of
  525. which the few characters are a subset. eg, SPE will match SPENCER, SPEND,
  526. etc. To do this, I call the 'seek' functions with a function which returns
  527. a match if the first string is a subset of the second. The critical point
  528. is that, no matter what search algorithm I use within these routines, the
  529. function parsed to 'seek' should be able to find all records given that
  530. the database is indexed according to the function parsed to 'open'.
  531.  
  532. Make sense? Didn't think so. Doesn't make sense to me either, but it works.
  533.  
  534. Parameters
  535.     r        A pointer to the memory area to find.
  536.     func    A pointer to the comparison function to use.
  537.  
  538. Returns
  539.     The record number it was found at, if it was, or -1 if either there
  540.     is no currently active database, or the record was not found.
  541.  
  542. -------------------------------------------------------------------------------
  543. Function        DBseeknext
  544. Prototype in    db.h
  545. Module            db
  546. Library            dbl
  547.  
  548. int        DBseeknext(void *r,int (*func)(void *,void *))
  549.  
  550. See DBseekfirst
  551.  
  552. Parameters
  553.     r        A pointer to the memory area to find.
  554.     func    A pointer to the comparison function to use.
  555.  
  556. Returns
  557.     The record number it was found at, if it was, or -1 if either there
  558.     is no currently active database, or the record was not found.
  559.  
  560. -------------------------------------------------------------------------------
  561. Function        DBselect
  562. Prototype in    db.h
  563. Module            db
  564. Library            dbl
  565.  
  566. void    DBselect(DBfile *db)
  567.  
  568. Makes the specified database the active one.
  569.  
  570. Parameters
  571.     db        A pointer to the DBfile structure for the desired database.
  572.  
  573. Returns
  574.     Nothing
  575.  
  576. -------------------------------------------------------------------------------
  577. Function        DBskip
  578. Prototype in    db.h
  579. Module            db
  580. Library            dbl
  581.  
  582. int        DBskip(int n)
  583.  
  584. Moves the current record indicator for the currently active database
  585. forward or backward the specified number of records. The move can be
  586. off the top or bottom of the file, but no further. ie, it will not
  587. cycle around from top to bottom or vice-versa.
  588.  
  589. Parameters
  590.     n        The number of records to skip. A positive value will move
  591.             forward in the file, while a negative value will move
  592.             backward. A zero value will have no effect.
  593.  
  594. Returns
  595.     The new current record indicator if there is a currently active
  596.     database, or -1 if there isn't. Note that skipping past the top
  597.     or bottom of the file will return the Before-Top (-1) or After-Bottom
  598.     (too large) indicators.
  599.  
  600. -------------------------------------------------------------------------------
  601. Function        DBtop
  602. Prototype in    db.h
  603. Module            db
  604. Library            dbl
  605.  
  606. int        DBtop(void)
  607.  
  608. Returns the record number of the first record in the currently active
  609. database file.
  610.  
  611. Parameters
  612.     None
  613.  
  614. Returns
  615.     The first record number if there is a currently active database file,
  616.     or -1 if there isn't.
  617.  
  618. -------------------------------------------------------------------------------
  619. Function        DBvalid
  620. Prototype in    db.h
  621. Module            db
  622. Library            dbl
  623.  
  624. int        DBvalid(void)
  625.  
  626. Returns the validity of the current record indicator in the currently
  627. active database.
  628.  
  629. Parameters
  630.     none
  631.  
  632. Returns
  633.     TRUE if the current record indicator is valid, or FALSE if it isn't.
  634.  
  635. -------------------------------------------------------------------------------
  636. Function        DBwrite
  637. Prototype in    db.h
  638. Module            db
  639. Library            dbl
  640.  
  641. int        DBwrite(void *r)
  642.  
  643. Writes the specified memory area to the current record in the currently
  644. active database file.
  645.  
  646. Parameters
  647.     r        A pointer to the record to write.
  648.  
  649. Returns
  650.     The current record number if the operation was successful, or -1 if
  651.     it wasn't.
  652.  
  653. -------------------------------------------------------------------------------
  654. Function        IFCallin
  655. Prototype in    ifc.h
  656. Module            ifc
  657. Library            tll
  658.  
  659. int16    IFCallin(void)
  660.  
  661. This function is similar to IFCin, except that it inputs from all 9
  662. possible input pins instead of just 8. The bits in the returned value are :
  663.  
  664. Bit        Pin
  665. 0        1
  666. 1        14
  667. 2        16
  668. 3        17
  669. 4        15
  670. 5        13
  671. 6        12
  672. 7        10
  673. 8        11
  674.  
  675. A ground on the given pin will return a 1 in the appropriate bit position,
  676. while a 0 is returned if the pin is floating or tied to +5v. Note that
  677. some of the pins are inverted. This is corrected in this routine by
  678. exclusive-Oring the read value before returning. Also, to gain a valid
  679. return value, the programmer should make sure the following function
  680. call is made :
  681.  
  682. IFCallout(0x0400);
  683.  
  684. Since the lower 4 bits of the input value are taken from an open-collector
  685. output chip, the chip must have the correct values output to it's pins
  686. before reading. The above call accomplishes this. It also resets the
  687. remaining output pins (lower 8 bits). This does not need to be done, as
  688. long as bit 10 is set and bits 8,9 and 11 are reset.
  689.  
  690. Parameters
  691.     none
  692.  
  693. Returns
  694.     The bits read, or -1 if the port is not installed.
  695.  
  696. -------------------------------------------------------------------------------
  697. Function        IFCallout
  698. Prototype in    ifc.h
  699. Module            ifc
  700. Library            tll
  701.  
  702. int16    IFCallout(uint16 val)
  703.  
  704. This function is similar to IFCout, except that it outputs to all 12
  705. possible output pins instead of just 8. The bits are output onto the
  706. following pins :
  707.  
  708. Bit        Pin
  709. 0        2
  710. 1        3
  711. 2        4
  712. 3        5
  713. 4        6
  714. 5        7
  715. 6        8
  716. 7        9
  717. 8        1
  718. 9        14
  719. 10        16
  720. 11        17
  721.  
  722. Parameters
  723.     val        The binary value to ouput, of which the lower 12 bits are used.
  724.  
  725. Returns
  726.     The result of the output operation, as read from the port, or -1
  727.     if the port is not installed.
  728.  
  729. -------------------------------------------------------------------------------
  730. Function        IFCin
  731. Prototype in    ifc.h
  732. Module            ifc
  733. Library            tll
  734.  
  735. int16    IFCin(void)
  736.  
  737. This function reads the current status of eight input lines from the
  738. current port, and returns the value. The bits in the returned value are :
  739.  
  740. Bit        Pin
  741. 0        1
  742. 1        14
  743. 2        16
  744. 3        15
  745. 4        13
  746. 5        12
  747. 6        10
  748. 7        11
  749.  
  750. Note : Ground (relative to pin 25) on any pin will produce a 0 in the
  751.         corresponding bit position, while +5v will produce a 1. With
  752.         some printer boards, a floating pin will consistently produce
  753.         a 1, while with others it varies.
  754.  
  755. Parameters
  756.     none
  757.  
  758. Returns
  759.     The bits read, or -1 if the port is not installed.
  760.  
  761. -------------------------------------------------------------------------------
  762. Function        IFCout
  763. Prototype in    ifc.h
  764. Module            ifc
  765. Library            tll
  766.  
  767. int16    IFCout(uint8 val)
  768.  
  769. This function outputs the 8-bit value 'val' to the current port.
  770. The bits are output onto the following pins :
  771.  
  772. Bit        Pin
  773. 0        2
  774. 1        3
  775. 2        4
  776. 3        5
  777. 4        6
  778. 5        7
  779. 6        8
  780. 7        9
  781.  
  782. Note : A '1' in any bit position will produce +5v on the appropriate line,
  783.         while a '0' will drop it to ground, relative to pin 25. These
  784.         voltages will stay until a different value is written.
  785.  
  786. Parameters
  787.     val        The binary value to output.
  788.  
  789. Returns
  790.     The result of the output operation, as read from the port, or -1
  791.     if the port is not installed.
  792.  
  793. -------------------------------------------------------------------------------
  794. Function        IFCset
  795. Prototype in    ifc.h
  796. Module            ifc
  797. Library            tll
  798.  
  799. int        IFCset(int lpt)
  800.  
  801. This function sets the printer port to use. It simply checks for a valid
  802. input value and sets IFClpt to that value. This value is used in the
  803. functions 'IFCin' and 'IFCout'.
  804.  
  805. Parameters
  806.     lpt        The port to use. Range from 0 (LPT1) to 3 (LPT4).
  807.  
  808. Returns
  809.     TRUE if the port is installed, FALSE if it isn't.
  810.  
  811. -------------------------------------------------------------------------------
  812. Function        KBcheck
  813. Prototype in    kb.h
  814. Module            kb
  815. Library            wnl
  816.  
  817. int        KBcheck(void)
  818.  
  819. Checks to see whether a key has been pressed.
  820.  
  821. Parameters
  822.     none
  823.  
  824. Returns
  825.     TRUE if a key has been pressed, or FALSE if it hasn't.
  826.  
  827. -------------------------------------------------------------------------------
  828. Function        KBgetc
  829. Prototype in    kb.h
  830. Module            kb
  831. Library            wnl
  832.  
  833. uchar    KBgetc(char *c,char *s,int f)
  834.  
  835. Gets a single character response from the keyboard. The key pressed is
  836. stored in the location pointed to by 'c', and the valid reponses are
  837. limited to characters in the string 's'. The flag 'f' determines the
  838. characteristics of the input function as follows :
  839.  
  840. K_UPPER        Convert all keystrokes to uppercase.
  841. K_BELL        Sound the console bell on an invalid response.
  842. K_RETURN    Return a <CR> for the function instead of the character.
  843.             The character is still stored in 'c'.
  844.  
  845. Parameters
  846.     c        A pointer to the location to store the character.
  847.     s        A pointer to a string containing valid characters.
  848.     f        The flags above, ORed together.
  849.  
  850. Returns
  851.     The character entered, or <CR> if K_RETURN is set.
  852.  
  853. -------------------------------------------------------------------------------
  854. Function        KBgetch
  855. Prototype in    kb.h
  856. Module            kb
  857. Library            wnl
  858.  
  859. uchar    KBgetch(void)
  860.  
  861. Wait for a keypress and return the key's value.
  862.  
  863. Parameters
  864.     none
  865.  
  866. Returns
  867.     The key pressed.
  868.  
  869. -------------------------------------------------------------------------------
  870. Function        KBgetn
  871. Prototype in    kb.h
  872. Module            kb
  873. Library            wnl
  874.  
  875. uchar    KBgetn(double *n,uint w,uint d)
  876.  
  877. Gets a number from the keyboard at the current screen coordinates. Uses
  878. the WN functions for displaying.
  879.  
  880. Parameters
  881.     n        A pointer to the number to be edited (a double).
  882.     w        The total width of the number to be edited, including the
  883.             decimal point.
  884.     d        The number of decimal places in the number to be edited.
  885.  
  886. Returns
  887.     The last key pressed before exiting the function.
  888.  
  889. -------------------------------------------------------------------------------
  890. Function        KBgets
  891. Prototype in    kb.h
  892. Module            kb
  893. Library            wnl
  894.  
  895. uchar    KBgets(char *s,uint l,int f)
  896.  
  897. Gets a string from the keyboard at the current screen coordinates.
  898. Uses the WN functions for displaying. The only valid value for 'f' is
  899. K_UPPER, which converts all keys to uppercase.
  900.  
  901. Parameters
  902.     s        A pointer to the string to be edited.
  903.     l        The length of the string to be edited.
  904.     f        The flags.
  905.  
  906. Returns
  907.     The last key pressed before exiting the function.
  908.  
  909. -------------------------------------------------------------------------------
  910. Function        KBnwgetch
  911. Prototype in    kb.h
  912. Module            kb
  913. Library            wnl
  914.  
  915. uchar    KBnwgetch()
  916.  
  917. Check to see whether a key has been pressed, and if so, return it's
  918. value.
  919.  
  920. Parameters
  921.     none
  922.  
  923. Returns
  924.     The key pressed if there was one, or zero if there wasn't.
  925.  
  926. -------------------------------------------------------------------------------
  927. Function        KBsetfunc
  928. Prototype in    kb.h
  929. Module            kb
  930. Library            wnl
  931.  
  932. void    KBsetfunc(void (*func)(void))
  933.  
  934. Sets the function to be called while waiting for a keypress.
  935.  
  936. Parameters
  937.     func    The function to be called, or NULL for no function.
  938.  
  939. Returns
  940.     nothing
  941.  
  942. -------------------------------------------------------------------------------
  943. Function        KBsettrap
  944. Prototype in    kb.h
  945. Module            kb
  946. Library            wnl
  947.  
  948. void    KBsettrap(uchar key,void (*func)(void))
  949.  
  950. Sets a key to be looked for while waiting for input, and a function to
  951. be called if it's seen.
  952.  
  953. Parameters
  954.     key        The key to look for.
  955.     func    The function to call when it's found.
  956.  
  957. Returns
  958.     nothing
  959.  
  960. -------------------------------------------------------------------------------
  961. Function        KKend
  962. Prototype in    kk.h
  963. Module            kk
  964. Library            gml
  965.  
  966. void    KKend(void)
  967.  
  968. Resets the vectors to the way they were originally.
  969.  
  970. Parameters
  971.     none
  972.  
  973. Returns
  974.     nothing
  975.  
  976. -------------------------------------------------------------------------------
  977. Function        KKget
  978. Prototype in    kk.h
  979. Module            kk
  980. Library            gml
  981.  
  982. int        KKget(uchar scan)
  983.  
  984. Returns the current state of the key with the specified scan code.
  985.  
  986. Parameters
  987.     scan    The scan code of the key to check.
  988.  
  989. Returns
  990.     TRUE if the key is currently pressed, or FALSE if it isn't.
  991.  
  992. -------------------------------------------------------------------------------
  993. Function        KKhandler
  994. Prototype in    kk.h
  995. Module            kk
  996. Library            gml
  997.  
  998. void    interrupt KKhandler(void)
  999.  
  1000. This is the new interrupt 9 handler. It merely sets or resets the
  1001. appropriate byte in the keyboard table, based on the scan code presented.
  1002. There is a call to the old interrupt 9 handler commented out. This is
  1003. because I assume that if you are using this one, you don't want normal
  1004. keyboard actions (such as the buffer filling since you're not reading it)
  1005. to occur. If you want them to, remove the comments around the 'old09()'
  1006. statement, and place them around the 'kbreset()' statement. This may be
  1007. implemented as a parameter to 'newkeyinit()' later.
  1008.  
  1009. Parameters
  1010.     none
  1011.  
  1012. Returns
  1013.     nothing
  1014.  
  1015. -------------------------------------------------------------------------------
  1016. Function        KKinit
  1017. Prototype in    kk.h
  1018. Module            kk
  1019. Library            gml
  1020.  
  1021. void    KKinit(void)
  1022.  
  1023. Initialises the new keyboard handler. First checks the value of 'old09'
  1024. to make sure it hasn't already been called. Then sets vectors, and does
  1025. an 'atexit' call to make sure the vectors are swapped back before exiting
  1026. the program. The 'newkeyend()' function can be called explicitly, as it
  1027. also checks the value of 'old09'. The 'atexit' function could be removed,
  1028. as long as you remember to call 'newkeyend' yourself. Also, this function
  1029. zeroes the current contents of the keyboard flags buffer.
  1030.  
  1031. Parameters
  1032.     none
  1033.  
  1034. Returns
  1035.     nothing
  1036.  
  1037. -------------------------------------------------------------------------------
  1038. Function        KKreset
  1039. Prototype in    kk.h
  1040. Module            kk
  1041. Library            gml
  1042.  
  1043. void    KKreset(uchar scan)
  1044.  
  1045. Sets the flag for the specified key to FALSE
  1046.  
  1047. Parameters
  1048.     scan    The scan code of the key to set.
  1049.  
  1050. Returns
  1051.     nothing
  1052.  
  1053. -------------------------------------------------------------------------------
  1054. Function        KKset
  1055. Prototype in    kk.h
  1056. Module            kk
  1057. Library            gml
  1058.  
  1059. void    KKset(uchar scan)
  1060.  
  1061. Sets the flag for the specified key to TRUE
  1062.  
  1063. Parameters
  1064.     scan    The scan code of the key to set.
  1065.  
  1066. Returns
  1067.     nothing
  1068.  
  1069. -------------------------------------------------------------------------------
  1070. Function        MNcolor
  1071. Prototype in    mn.h
  1072. Module            mn
  1073. Library            wnl
  1074.  
  1075. void    MNcolor(uint norm,uint high)
  1076.  
  1077. Set the menu colors. 'n' specifies the normal text color,
  1078. and 'h' the highlighted text color.
  1079.  
  1080. Parameters
  1081.     norm    The normal menu color.
  1082.     high    The highlighted menu color.
  1083.  
  1084. Returns
  1085.     nothing
  1086.  
  1087. -------------------------------------------------------------------------------
  1088. Function        MNmenu
  1089. Prototype in    mn.h
  1090. Module            mn
  1091. Library            wnl
  1092.  
  1093. uchar    MNmenu(MNdata *mn)
  1094.  
  1095. Initiate the menu system, from the data pointed to by 'mn'.
  1096.  
  1097. Parameters
  1098.     mn        A pointer to the MNdata structure defined in mn.h holding
  1099.             the menu definition.
  1100.  
  1101. Returns
  1102.     The last character entered before terminating this function.
  1103.  
  1104. -------------------------------------------------------------------------------
  1105. Function        MNselect
  1106. Prototype in    mn.h
  1107. Module            mn
  1108. Library            wnl
  1109.  
  1110. uchar    MNselect(uint ncolor,uint hcolor,int min,int max,int *option,
  1111.                 void (*func)(uint,uint))
  1112.  
  1113. Select an item from a list.
  1114.  
  1115. Parameters
  1116.     ncolor    The color to use for normal text.
  1117.     hcolor    The color to use for highlighted text.
  1118.     min        The lowest valid value for 'option'.
  1119.     max        The highest valid value for 'option'.
  1120.     option    A pointer to an integer which holds the current item number on
  1121.             entry to this function, and the selected item on exit.
  1122.     func    A pointer to the function which displays the current item.
  1123.  
  1124. Returns
  1125.     The last character entered before terminating this function.
  1126.  
  1127. -------------------------------------------------------------------------------
  1128. Function        PKaccess_type
  1129. Prototype in    pk.h
  1130. Module            pk
  1131. Library            netl
  1132.  
  1133. int        PKaccess_type(int if_class,int if_type,int if_number,char far *type,
  1134.                     uint typelen,void interrupt (*receiver)())
  1135.  
  1136. Initiates  access to packets of the specified type.  The argument type is a
  1137. pointer to a packet type specification.  The argument typelen is the length
  1138. in  bytes  of  the  type  field.  The argument receiver is a pointer  to  a
  1139. subroutine  which  is  called when a packet is received.   If  the  typelen
  1140. argument  is  0,  this indicates that the caller wants to match all packets
  1141. (match all requests may  be  refused by packet drivers developed to conform
  1142. to versions of this spec previous to 1.07).
  1143.  
  1144. When a packet is received, receiver  is  called twice by the packet driver.
  1145. The first  time  it  is  called to request a buffer from the application to
  1146. copy the packet into.  AX == 0 on this call.  The application should return
  1147. a pointer to the buffer in ES:DI.  If the application  has  no    buffers, it
  1148. may return 0:0 in ES:DI, and  the  driver  should throw away the packet and
  1149. not perform the second call.
  1150.  
  1151. It is important  that  the packet length (CX) be valid on the AX == 0 call,
  1152. so that the receiver can allocate a buffer of the proper size.    This length
  1153. (as well as the copy  performed prior to the AX == 1 call) must include the
  1154. MAC header and all received data, but not the trailing Frame Check Sequence
  1155. (if any).
  1156.  
  1157. On  the  second  call, AX == 1.  This call indicates that the copy has been
  1158. completed, and the application may do  as  it  wishes with the buffer.    The
  1159. buffer that the packet was copied into is pointed to by DS:SI.
  1160.  
  1161. Parameters
  1162.     if_class    Class of the interface.
  1163.     if_type        Type of the interface.
  1164.     if_number    Number of the interface.
  1165.     type        Pointer to the desired packet type.
  1166.     typelen        Length of the desired packet type.
  1167.     receiver    Pointer to function to call on receipt of an incoming
  1168.                 packet.
  1169.  
  1170. Returns
  1171.     AX register if operation successful, or -1 if it wasn't.
  1172.  
  1173. Possible errors
  1174.         NO_CLASS
  1175.         NO_TYPE
  1176.         NO_NUMBER
  1177.         BAD_TYPE
  1178.         NO_SPACE
  1179.         TYPE_INUSE
  1180.  
  1181. -------------------------------------------------------------------------------
  1182. Function        PKas_send_pkt
  1183. Prototype in    pk.h
  1184. Module            pk
  1185. Library            netl
  1186.  
  1187. int        PKas_send_pkt(char far *buf,uint len,
  1188.                     void interrupt (*upcall)(int result,char far *buffer))
  1189.  
  1190. as_send_pkt()  differs    from  send_pkt() in that the  upcall()    routine  is
  1191. called when the application's data has    been  copied out of the buffer, and
  1192. the application can safely modify or re-use the  buffer.    The  driver may
  1193. pass a non-zero error code to  upcall()  if  the copy failed, or some other
  1194. error  was  detected,  otherwise  it  should indicate success, even if    the
  1195. packet hasn't actually been  transmitted  yet.    Note that the buffer passed
  1196. to send_pkt() is assumed  to  be modifiable when that call returns, whereas
  1197. with as_send_pkt(), the buffer may be  queued  by the driver and dealt with
  1198. later.    If an error is returned on the initial call, the upcall will not be
  1199. executed.  This function was added in v1.09 of this specification,  and may
  1200. not be implemented by all drivers (see driver_info()).
  1201.  
  1202. The upcall() routine is called with the status in AX, and a pointer to the
  1203. original buffer area in ES:DI.
  1204.  
  1205. Parameters
  1206.     buf        Pointer to the area containing the data to transmit.
  1207.     len        Length of the data to transmit.
  1208.     upcall    Function to call when buffer re-usable.
  1209.  
  1210. Returns
  1211.     TRUE if the operation was successful, or FALSE if it wasn't.
  1212.  
  1213. Possible errors
  1214.         CANT_SEND        (transmit error, re-entered, etc.)
  1215.         BAD_COMMAND        (Level 0 or 1 driver)
  1216.  
  1217. -------------------------------------------------------------------------------
  1218. Function        PKcheck_int
  1219. Prototype in    pk.h
  1220. Module            pk
  1221. Library            netl
  1222.  
  1223. int        PKcheck_int(int intnum)
  1224.  
  1225. Checks for the existence of a packet driver at the spcified interrupt
  1226. vector.
  1227.  
  1228. Parameters
  1229.     intnum    The interrupt vector to check.
  1230.  
  1231. Returns
  1232.     TRUE if there is a driver at that vector, or FALSE if there isn't.
  1233.  
  1234. -------------------------------------------------------------------------------
  1235. Function        PKdriver_info
  1236. Prototype in    pk.h
  1237. Module            pk
  1238. Library            netl
  1239.  
  1240. PKinfo    far *PKdriver_info(int handle)
  1241.  
  1242. This  function returns information about the interface.    The    version  is
  1243. assumed to be an internal hardware driver identifier.  In  earlier versions
  1244. of  this  spec, the handle argument (which  must  have    been  obtained    via
  1245. access_type()) was required.   It  is  now  optional, but drivers developed
  1246. according to versions  of  this  spec  previous  to 1.07 may require it, so
  1247. implementers should take care.
  1248.  
  1249. Parameters
  1250.     handle    Handle returned from access_type.
  1251.  
  1252. Returns
  1253.     Pointer to a locally declared static PKinfo structure defined in pkt.h
  1254.     containing the information if available, or NULL if not. This structure
  1255.     is overwritten with each call to this function.
  1256.  
  1257. Possible errors
  1258.         BAD_HANDLE            (older drivers only)
  1259.  
  1260. -------------------------------------------------------------------------------
  1261. Function        PKerror
  1262. Prototype in    pk.h
  1263. Module            pk
  1264. Library            netl
  1265.  
  1266. void    PKerror(int err)
  1267.  
  1268. Generates an error condition. If 'err' == 0, the last error returned
  1269. from the driver is used, else 'err' is used to indicate the type of error.
  1270. The interface functions within this module always pass '0', but the user
  1271. program may wish to pass some other value to simulate an error. Also,
  1272. if the error was not generated by the packet driver (as in the case of
  1273. the initialise() function), PKerror can be called with a non-zero value.
  1274.  
  1275. Parameters
  1276.     err        The error number to generate, or 0 to generate the last
  1277.             error from the driver.
  1278.  
  1279. Returns
  1280.     Nothing
  1281.  
  1282. -------------------------------------------------------------------------------
  1283. Function        PKget_address
  1284. Prototype in    pk.h
  1285. Module            pk
  1286. Library            netl
  1287.  
  1288. int        PKget_address(int handle,char far *buf,int len)
  1289.  
  1290. Copies the current local net address of the interface into buf.  The buffer
  1291. buf is len bytes long.    The actual number of bytes  copied  is    returned in
  1292. CX.    If  the    NO_SPACE  error  is  returned, this indicates that len    was
  1293. insufficient to hold the local net address. If the address has been changed
  1294. by set_address(), the new address should be returned.
  1295.  
  1296. Parameters
  1297.     handle    Handle returned from access_type.
  1298.     buf        Pointer to area to store address in.
  1299.     len        Maximum length of area.
  1300.  
  1301. Returns
  1302.     The number of bytes copied if successful, or zero if not.
  1303.  
  1304. Possible errors
  1305.         BAD_HANDLE
  1306.         NO_SPACE
  1307.  
  1308. -------------------------------------------------------------------------------
  1309. Function        PKget_multicast_list
  1310. Prototype in    pk.h
  1311. Module            pk
  1312. Library            netl
  1313.  
  1314. int        PKget_multicast_list(char far *addrlist)
  1315.  
  1316. On a successful return, addrlst points to len bytes of    multicast addresses
  1317. currently in use.  The application program must not modify this information
  1318. in-place.  A NO_SPACE error indicates that there wasn't enough room for all
  1319. active multicast addresses.
  1320.  
  1321. Parameters
  1322.     addrlist    Pointer to an area to hold the multicast address list.
  1323.  
  1324. Returns
  1325.     The number of bytes copied if the operation was successful, or zero
  1326.     if it wasn't. The multicast address list is copied into the area
  1327.     pointed to by addrlist if possible.
  1328.  
  1329. Possible errors
  1330.         NO_MULTICAST
  1331.         NO_SPACE
  1332.  
  1333. -------------------------------------------------------------------------------
  1334. Function        PKget_parameters
  1335. Prototype in    pk.h
  1336. Module            pk
  1337. Library            netl
  1338.  
  1339. PKparam    far *PKget_parameters(void)
  1340.  
  1341. The performance of  an    application may benefit from using get_parameters()
  1342. to  obtain a number of driver parameters.  This function was added to v1.09
  1343. of this  specification,  and  may  not    be  implemented by all drivers (see
  1344. driver_info()).
  1345.  
  1346. The major_rev and minor_rev fields are the major and minor revision numbers
  1347. of the version    of  this  specification  the  driver conforms to.  For this
  1348. document, major_rev is    1 and minor_rev is 9.  The length field may be used
  1349. to  determine  which values are valid, should  a  later  revision  of  this
  1350. specification  add  more  values at the end of this structure.      For  this
  1351. document,  length is 14. The addr_len field is the length of a MAC address,
  1352. in bytes. Note the param structure is assumed to be packed, such that these
  1353. fields occupy four consecutive bytes of storage.
  1354.  
  1355. In the param structure, the mtu is the maximum MAC-level packet  the driver
  1356. can  handle  (on Ethernet this number is fixed, but it may  vary  on  other
  1357. media, e.g. 802.5  or  FDDI).     The  multicast_aval field is the number of
  1358. bytes required to  store  all  the  multicast  addresses  supported  by any
  1359. "perfect filter" mechanism in the hardware.    Calling set_multicast_list()
  1360. with its len argument equal to this value should not  fail  with a NO_SPACE
  1361. error.    A value of zero implies no multicast support.
  1362.  
  1363. The rcv_bufs and xmt_bufs indicate the number of  back-to-back    receives or
  1364. transmits  the    card/driver  combination  can  accomodate,  minus  1.    The
  1365. application can use this information  to  adjust  flow-control    or transmit
  1366. strategies.  A single-buffered card (for example, an Interlan NI5010) would
  1367. normally return 0 in both fields. A value of 0 in  rcv_bufs  could  also be
  1368. used by a driver author to indicate that the hardware has limitations which
  1369. prevent  it  from  receiving  as  fast    as  other systems can send, and  to
  1370. recommend that the  upper-layer  protocols invoke lock-step flow control to
  1371. avoid packet loss.
  1372.  
  1373. The  int_num  field  should  be  set  to  a  hardware  interrupt  that    the
  1374. application can hook in order to perform interrupt-time protocol processing
  1375. after the EOI has been sent to the 8259 interrupt  controller  and the card
  1376. is  ready for more interrupts.    A value of zero indicates that there is  no
  1377. such interrupt.  Any application hooking this interrupt and finding  a non-
  1378. zero value in the vector must  pass  the  interrupt down the chain and wait
  1379. for  its  predecessors    to return before performing any processing or stack
  1380. switches.  Any    driver    which  implements  this function via a separate INT
  1381. instruction and vector, instead of  just using the hardware interrupt, must
  1382. prevent any saved context from being overwritten by a later interrupt.     In
  1383. other words,  if  the  driver  switches to its own stack, it must allow re-
  1384. entrancy.
  1385.  
  1386. Parameters
  1387.     none
  1388.  
  1389. Returns
  1390.     Pointer to a locally declared static PKparam structure defined in pkt.h
  1391.     containing the information if available, or NULL if not. This structure
  1392.     is overwritten with each call to this function.
  1393.  
  1394. Possible errors
  1395.         BAD_COMMAND            (No high-performance support)
  1396.  
  1397. -------------------------------------------------------------------------------
  1398. Function        PKget_rcv_mode
  1399. Prototype in    pk.h
  1400. Module            pk
  1401. Library            netl
  1402.     
  1403. int        PKget_rcv_mode(int handle)
  1404.  
  1405. Returns the current receive mode of the interface associated with handle.
  1406.  
  1407. Parameters
  1408.     handle    Handle returned from access_type.
  1409.  
  1410. Returns
  1411.     The receive mode if available, or -1 if not.
  1412.  
  1413. Possible errors
  1414.         BAD_HANDLE
  1415.  
  1416. -------------------------------------------------------------------------------
  1417. Function        PKget_statistics
  1418. Prototype in    pk.h
  1419. Module            pk
  1420. Library            netl
  1421.  
  1422. PKstat    far *PKget_statistics(int handle)
  1423.  
  1424. Returns a pointer to a statistics structure for the interface.     The values
  1425. are stored as to be normal 80xx 32-bit integers.
  1426.  
  1427. Parameters
  1428.     handle    Handle returned from access_type.
  1429.  
  1430. Returns
  1431.     Pointer to a locally declared static PKstat structure defined in pkt.h
  1432.     containing the information if available, or NULL if not. This structure
  1433.     is overwritten with each call to this function.
  1434.  
  1435. Possible errors
  1436.         BAD_HANDLE
  1437.  
  1438. -------------------------------------------------------------------------------
  1439. Function        PKinit
  1440. Prototype in    pk.h
  1441. Module            pk
  1442. Library            netl
  1443.  
  1444. int        PKinit(void)
  1445.  
  1446. Sets up internal variables for the driver functions to use. Must be
  1447. called prior to calling any other routines in this module.
  1448.  
  1449. Parameters
  1450.     none
  1451.  
  1452. Returns
  1453.     The interrupt number for the packet driver if one was found, or
  1454.     zero if there isn't one.
  1455.  
  1456. -------------------------------------------------------------------------------
  1457. Function        PKrelease_type
  1458. Prototype in    pk.h
  1459. Module            pk
  1460. Library            netl
  1461.  
  1462. int        PKrelease_type(int handle)
  1463.  
  1464. This function ends access  to  packets associated with a handle returned by
  1465. access_type().    The handle is no longer valid.
  1466.  
  1467. Parameters
  1468.     handle    Handle returned from access_type.
  1469.  
  1470. Returns
  1471.     TRUE if the operation was successful, or FALSE if it wasn't.
  1472.  
  1473. Possible errors
  1474.         BAD_HANDLE
  1475.  
  1476. -------------------------------------------------------------------------------
  1477. Function        PKreset_interface
  1478. Prototype in    pk.h
  1479. Module            pk
  1480. Library            netl
  1481.  
  1482. int        PKreset_interface(int handle)
  1483.  
  1484. Resets the interface associated with handle to a known state,  aborting any
  1485. transmits in process and reinitializing the receiver. The local net address
  1486. is  reset to the default (from ROM), the multicast list is cleared, and the
  1487. receive mode is set to 3 (own address & broadcasts).    If multiple handles
  1488. are open, these actions  might    seriously  disrupt other applications using
  1489. the interface, so CANT_RESET should be returned.
  1490.  
  1491. Parameters
  1492.     handle    Handle returned from access_type.
  1493.  
  1494. Returns
  1495.     TRUE if the operation was successful, or FALSE if it wasn't.
  1496.  
  1497. Possible errors
  1498.         BAD_HANDLE
  1499.         CANT_RESET
  1500.  
  1501. -------------------------------------------------------------------------------
  1502. Function        PKsend_pkt
  1503. Prototype in    pk.h
  1504. Module            pk
  1505. Library            netl
  1506.  
  1507. int        PKsend_pkt(char far *buf,uint len)
  1508.  
  1509. Transmits length bytes of  data,  starting at buffer.  The application must
  1510. supply the entire packet, including local network headers.  Any MAC  or LLC
  1511. information in use  for  packet  demultiplexing  (e.g.    the DEC-Intel-Xerox
  1512. Ethertype) must be filled in by  the  application  as well.  This cannot be
  1513. performed  by  the  driver,  as  no  handle is specified in a call  to    the
  1514. send_packet() function.
  1515.  
  1516. Parameters
  1517.     buf        Pointer to the data to be sent.
  1518.     len        Length of the data to be sent.
  1519.  
  1520. Returns
  1521.     TRUE if the operation was successful, or FALSE if it wasn't.
  1522.  
  1523. Possible errors
  1524.         CANT_SEND
  1525.  
  1526. -------------------------------------------------------------------------------
  1527. Function        PKset_address
  1528. Prototype in    pk.h
  1529. Module            pk
  1530. Library            netl
  1531.  
  1532. int        PKset_address(char far *addr,int len)
  1533.  
  1534. This call  is  used  when  the application or protocol stack needs to use a
  1535. specific  LAN  address.   For instance, DECnet protocols on Ethernet encode
  1536. the protocol address in the Ethernet address, requiring that it be set when
  1537. the protocol  stack  is  loaded.    A  BAD_ADDRESS error indicates that the
  1538. Packet Driver  doesn't    like  the  len (too short or too long), or the data
  1539. itself.  Note that packet drivers should refuse to change the address (with
  1540. a  CANT_SET error) if more than one handle is open (lest it be changed    out
  1541. from under another protocol stack).
  1542.  
  1543. Parameters
  1544.     addr    Pointer to the address to be set.
  1545.     len        Length of the address to be set.
  1546.  
  1547. Returns
  1548.     The number of bytes actually copied if the operation was successful,
  1549.     or zero if it wasn't.
  1550.  
  1551. Possible errors
  1552.         CANT_SET
  1553.         BAD_ADDRESS
  1554.  
  1555. -------------------------------------------------------------------------------
  1556. Function        PKset_multicast_list
  1557. Prototype in    pk.h
  1558. Module            pk
  1559. Library            netl
  1560.  
  1561. int        PKset_multicast_list(char far *addrlist,int len)
  1562.  
  1563. The addrlst argument is assumed to point to an len-byte buffer containing a
  1564. number of multicast addresses.      BAD_ADDRESS is returned if len modulo the
  1565. size of an address is  not equal to 0, or the data is unacceptable for some
  1566. reason.   NO_SPACE is returned (and no addresses are set) if there are more
  1567. addresses than the hardware supports directly.
  1568.  
  1569. The recommended procedure for  setting    multicast  addresses  is to issue a
  1570. get_multicast_list(),  copy  the  information to a local  buffer,  add    any
  1571. addresses  desired,  and  issue  a  set_multicast_list().  This  should  be
  1572. reversed when the application exits.  If the set_multicast_list() fails due
  1573. to NO_SPACE, use set_rcv_mode() to set mode 5 instead.
  1574.  
  1575. Parameters
  1576.     addrlist    Pointer to the multicast address list.
  1577.     len            Length of the multicast address list.
  1578.  
  1579. Returns
  1580.     TRUE if the operation was successful, or FALSE if it wasn't.
  1581.  
  1582. Possible errors
  1583.         NO_MULTICAST
  1584.         NO_SPACE
  1585.         BAD_ADDRESS
  1586.  
  1587. -------------------------------------------------------------------------------
  1588. Function        PKset_rcv_mode
  1589. Prototype in    pk.h
  1590. Module            pk
  1591. Library            netl
  1592.     
  1593. int        PKset_rcv_mode(int handle,int mode)
  1594.  
  1595. Sets  the  receive  mode  on  the  interface  associated with  handle.    The
  1596. following values are accepted for mode:
  1597.  
  1598. mode    meaning
  1599.  
  1600. 1        turn off receiver
  1601. 2        receive only packets sent to this interface
  1602. 3        mode 2 plus broadcast packets
  1603. 4        mode 3 plus limited multicast packets
  1604. 5        mode 3 plus all multicast packets
  1605. 6        all packets
  1606.  
  1607. Note that not all interfaces support  all  modes.  The receive mode affects
  1608. all  packets  received    by this interface, not just packets associated with
  1609. the   handle   argument.       See    the    extended     driver   functions
  1610. get_multicast_list()  and  set_multicast_list()  for  programming  "perfect
  1611. filters" to receive specific multicast addresses.
  1612.  
  1613. Note  that mode 3 is the default, and if the set_rcv_mode() function is not
  1614. implemented, mode 3 is assumed to be in force as long  as  any    handles are
  1615. open (from the first access_type() to the last release_type()).
  1616.  
  1617. Parameters
  1618.     handle    Handle returned from access_type.
  1619.     mode    Desired receive mode.
  1620.  
  1621. Returns
  1622.     TRUE if the operation was successful, or FALSE if it wasn't.
  1623.  
  1624. Possible errors
  1625.         BAD_HANDLE
  1626.         BAD_MODE
  1627.  
  1628. -------------------------------------------------------------------------------
  1629. Function        PKseterr
  1630. Prototype in    pk.h
  1631. Module            pk
  1632. Library            netl
  1633.  
  1634. void    PKseterr(void (*func)())
  1635.  
  1636. Sets the function to be called when an error condition is generated.
  1637. Whenever PKerror is called, it checks to see if a function has been
  1638. set, and calls it with the error number and the appropriate error
  1639. string as parameters. The function should be declared as one of the
  1640. following :
  1641.  
  1642. void    func(void);
  1643. void    func(char *errstring);
  1644. void    func(char *errstring,int errnumber);
  1645.  
  1646. It has been designed this way so that, in the simplest case, the command
  1647. PKseterror(puts) will cause any error messages to be simply displayed on
  1648. standard output. However, the application program can define and specify
  1649. a more complex function using both parameters if required.
  1650.  
  1651. Parameters
  1652.     func    The function to be called when an error is generated.
  1653.  
  1654. Returns
  1655.     Nothing
  1656.  
  1657. -------------------------------------------------------------------------------
  1658. Function        PKterminate
  1659. Prototype in    pk.h
  1660. Module            pk
  1661. Library            netl
  1662.  
  1663. int        PKterminate(int handle)
  1664.  
  1665. Terminates the driver associated with handle.  If possible, the driver will
  1666. exit and allow MS-DOS to reclaim the memory it was using.
  1667.  
  1668. Parameters
  1669.     handle    Handle returned from access_type.
  1670.  
  1671. Returns
  1672.     TRUE if the operation was successful, or FALSE if it wasn't.
  1673.  
  1674. Possible errors
  1675.         BAD_HANDLE
  1676.         CANT_TERMINATE
  1677.  
  1678. -------------------------------------------------------------------------------
  1679. Function        PRerror
  1680. Prototype in    pr.h
  1681. Module            pr
  1682. Library            tll
  1683.  
  1684. void    PRerror(int n)
  1685.  
  1686. Called by other PR functions to generate an error condition. Can also be
  1687. called by the programmer to simulate a printer error.
  1688.  
  1689. Parameters
  1690.     n        The error number to generate.
  1691.  
  1692. Returns
  1693.     nothing
  1694.  
  1695. -------------------------------------------------------------------------------
  1696. Function        PRprintf
  1697. Prototype in    pr.h
  1698. Module            pr
  1699. Library            tll
  1700.  
  1701. int        PRprintf(char *fmt,...)
  1702.  
  1703. Outputs the specified variables to the printer according to the format
  1704. string. The format specification is the same as for printf etc.
  1705.  
  1706. Parameters
  1707.     fmt        The format string.
  1708.     ...        The variables to print.
  1709.  
  1710. Returns
  1711.     The number of characters output, or EOF if an error occurred.
  1712.  
  1713. -------------------------------------------------------------------------------
  1714. Function        PRputs
  1715. Prototype in    pr.h
  1716. Module            pr
  1717. Library            tll
  1718.  
  1719. int        PRputs(char *s)
  1720.  
  1721. Outputs the specified string to the printer. Attempts to do it's own
  1722. checking of the printer to remove those nasty DOS critical error
  1723. messages. Works well enough, but I'm still not real happy with it.
  1724. Expect some changes to be made here.
  1725.  
  1726. Parameters
  1727.     s    The string to output
  1728.  
  1729. Returns
  1730.     The last character output, or EOF if an error occurred.
  1731.  
  1732. -------------------------------------------------------------------------------
  1733. Function        PRseterr
  1734. Prototype in    pr.h
  1735. Module            pr
  1736. Library            tll
  1737.  
  1738. void    PRseterr(void (*func)(char *))
  1739.  
  1740. Sets the function to be called when a printer error is generated. The
  1741. function should expect a pointer to a character string containing the
  1742. error message.
  1743.  
  1744. Parameters
  1745.     func    A pointer to the function to call.
  1746.  
  1747. Returns
  1748.     nothing
  1749.  
  1750. -------------------------------------------------------------------------------
  1751. Function        SCclear
  1752. Prototype in    sc.h
  1753. Module            sc
  1754. Library            wnl
  1755.  
  1756. int        SCclear(SCdata *sc)
  1757.  
  1758. Clears the fields on the screen defined in 'sc'.
  1759.  
  1760. -------------------------------------------------------------------------------
  1761. Function        SCdisplay
  1762. Prototype in    sc.h
  1763. Module            sc
  1764. Library            wnl
  1765.  
  1766. int        SCdisplay(SCdata *f)
  1767.  
  1768. Displays the field pointed to by 'f'.
  1769.  
  1770. -------------------------------------------------------------------------------
  1771. Function        SCgetfield
  1772. Prototype in    sc.h
  1773. Module            sc
  1774. Library            wnl
  1775.  
  1776. uchar    SCgetfield(SCdata *f)
  1777.  
  1778. Gets the field pointed to by 'f'.
  1779.  
  1780. -------------------------------------------------------------------------------
  1781. Function        SCgetscreen
  1782. Prototype in    sc.h
  1783. Module            sc
  1784. Library            wnl
  1785.  
  1786. uchar    SCgetscreen(SCdata *sc,int *cf)
  1787.  
  1788. Gets a screen of data from the user, using the array of field
  1789. structures pointed to by 'sc'. On entry, the current field is
  1790. set to 'cf', and on exit, 'cf' is set to the current field.
  1791.  
  1792. -------------------------------------------------------------------------------
  1793. Function        SCnf
  1794. Prototype in    sc.h
  1795. Module            sc
  1796. Library            wnl
  1797.  
  1798. int        SCnf(SCdata *sc)
  1799.  
  1800. Returns the number of fields in the screen pointed to by 'sc'.
  1801.  
  1802. -------------------------------------------------------------------------------
  1803. Function        SCshow
  1804. Prototype in    sc.h
  1805. Module            sc
  1806. Library            wnl
  1807.         
  1808. int        SCshow(SCdata *sc)
  1809.  
  1810. Displays the current screen defined by 'sc'.
  1811.  
  1812. -------------------------------------------------------------------------------
  1813. Function        WNback
  1814. Prototype in    wn.h
  1815. Module            wn
  1816. Library            wnl
  1817.  
  1818. void    WNback(int c)
  1819.  
  1820. Set the current window background color to 'c'.
  1821.  
  1822. -------------------------------------------------------------------------------
  1823. Function        WNbox
  1824. Prototype in    wn.h
  1825. Module            wn
  1826. Library            wnl
  1827.  
  1828. void    WNbox(int lef,int top,int rig,int bot,int type)
  1829.  
  1830. Draw a box from 'ulx','uly' to 'lrx','lry'. Box can be single
  1831. or double lined, as specified in 'attr'. 0 is single, 1 is
  1832. double.
  1833.  
  1834. -------------------------------------------------------------------------------
  1835. Function        WNclose
  1836. Prototype in    wn.h
  1837. Module            wn
  1838. Library            wnl
  1839.  
  1840. WNwin    *WNclose(void)
  1841.  
  1842. Close the current window and select the last opened window.
  1843. Removes the window from the screen if it was opened as a
  1844. popup window.
  1845.  
  1846. -------------------------------------------------------------------------------
  1847. Function        WNcolor
  1848. Prototype in    wn.h
  1849. Module            wn
  1850. Library            wnl
  1851.  
  1852. int        WNcolor(int c)
  1853.  
  1854. Set the current window color to 'c'.
  1855.  
  1856. -------------------------------------------------------------------------------
  1857. Function        WNcursor
  1858. Prototype in    wn.h
  1859. Module            wn
  1860. Library            wnl
  1861.  
  1862. void    WNcursor(int state)
  1863.  
  1864. Place the cursor at the absolute position 'posn'. 'posn' is
  1865. a value returned from WNgcursor.
  1866.  
  1867. -------------------------------------------------------------------------------
  1868. Function        WNdisplay
  1869. Prototype in    wn.h
  1870. Module            wn
  1871. Library            wnl
  1872.  
  1873. void    WNdisplay(int x,int y,char *mess)
  1874.  
  1875. Display the string pointed to by 's' in the current window
  1876. at coordinates 'x','y'.
  1877.  
  1878. -------------------------------------------------------------------------------
  1879. Function        WNend
  1880. Prototype in    wn.h
  1881. Module            wn
  1882. Library            wnl
  1883.  
  1884. void    WNend(void)
  1885.  
  1886. Close all windows and restore the DOS screen present before
  1887. WNinit was called. Should not be called by the programmer,
  1888. as it is set up as an 'atexit' function by WNinit.
  1889.  
  1890. -------------------------------------------------------------------------------
  1891. Function        WNfore
  1892. Prototype in    wn.h
  1893. Module            wn
  1894. Library            wnl
  1895.  
  1896. void    WNfore(int c)
  1897.  
  1898. Set the current window foreground color to 'c'.
  1899.  
  1900. -------------------------------------------------------------------------------
  1901. Function        WNgcursor
  1902. Prototype in    wn.h
  1903. Module            wn
  1904. Library            wnl
  1905.  
  1906. int        WNgcursor(void)
  1907.  
  1908. Get the current absolute cursor position.
  1909.  
  1910. -------------------------------------------------------------------------------
  1911. Function        WNhline
  1912. Prototype in    wn.h
  1913. Module            wn
  1914. Library            wnl
  1915.  
  1916. void    WNhline(int l,int r,int y,int f)
  1917.  
  1918. Draws a horizontal line (single or double) from l,y to r,y.
  1919.  
  1920. Parameters
  1921.     l    The left x-position of the line.
  1922.     r    The right x-position of the line.
  1923.     y    The y-position of the line.
  1924.     f    0 for a single line, or 1 for a double.
  1925.  
  1926. Returns
  1927.     nothing
  1928.  
  1929. -------------------------------------------------------------------------------
  1930. Function        WNinit
  1931. Prototype in    wn.h
  1932. Module            wn
  1933. Library            wnl
  1934.  
  1935. void    WNinit(void)
  1936.  
  1937. Initialise the Windowing System. Does not need to be called
  1938. by the programmer as all WN functions check for it first.
  1939.  
  1940. -------------------------------------------------------------------------------
  1941. Function        WNload
  1942. Prototype in    wn.h
  1943. Module            wn
  1944. Library            wnl
  1945.  
  1946. void    WNload(void)
  1947.  
  1948. Sets up window limits, screen color, and cursor position and
  1949. type as specified by the current window.
  1950.  
  1951. There are 4 things to be restored on entry to a window. The window
  1952. coordinates, the cursor position, the color, and the cursor type.
  1953.  
  1954. -------------------------------------------------------------------------------
  1955. Function        WNloadcurs
  1956. Prototype in    wn.h
  1957. Module            wn
  1958. Library            wnl
  1959.  
  1960. void    WNloadcurs(void)
  1961.  
  1962. Returns the cursor to the position previously saved by
  1963. WNsavecurs.
  1964.  
  1965. Set the current cursor position from two static variables (cursx,cursy).
  1966. These variables can only be seen within this module.
  1967.  
  1968. -------------------------------------------------------------------------------
  1969. Function        WNloaddos
  1970. Prototype in    wn.h
  1971. Module            wn
  1972. Library            wnl
  1973.  
  1974. void    WNloaddos(void)
  1975.  
  1976. Restore the DOS screen.
  1977.  
  1978. -------------------------------------------------------------------------------
  1979. Function        WNmessage
  1980. Prototype in    wn.h
  1981. Module            wn
  1982. Library            wnl
  1983.  
  1984. void    WNmessage(WNwin *win,int x,int y,int c,char *mess)
  1985.  
  1986. Place the character string 's' at the position 'x','y' in
  1987. the color 'c' in window 'w'.
  1988.  
  1989. -------------------------------------------------------------------------------
  1990. Function        WNopen
  1991. Prototype in    wn.h
  1992. Module            wn
  1993. Library            wnl
  1994.  
  1995. WNwin    *WNopen(int ulx,int uly,int lrx,int lry,int color,int attr,char *tit)
  1996.  
  1997. Open a window from 'ulx','uly' to 'lrx','lry'. Current
  1998. color is set to 'c', and attributes to 'attr'. 'attr' can
  1999. specify whether the window is a popup or not, as well as
  2000. the border style (None, single or double).
  2001.  
  2002. -------------------------------------------------------------------------------
  2003. Function        WNputc
  2004. Prototype in    wn.h
  2005. Module            wn
  2006. Library            wnl
  2007.  
  2008. void    WNputc(char ch)
  2009.  
  2010. Place the character 'c' in the current window.
  2011.  
  2012. -------------------------------------------------------------------------------
  2013. Function        WNsave
  2014. Prototype in    wn.h
  2015. Module            wn
  2016. Library            wnl
  2017.  
  2018. void    WNsave(void)
  2019.  
  2020. Save the current window parameters.
  2021.  
  2022. These are the only two variables not updated on an ongoing basis by
  2023. these routines. All of the display functions use the Turbo-C console
  2024. I/O routines, which can change the cursor position without updating
  2025. the xy coordinates stored in the 'curr' structure.
  2026.  
  2027. -------------------------------------------------------------------------------
  2028. Function        WNsavecurs
  2029. Prototype in    wn.h
  2030. Module            wn
  2031. Library            wnl
  2032.  
  2033. void    WNsavecurs(void)
  2034.  
  2035. Save the current cursor position to be restored later by
  2036. WNloadcurs.
  2037.  
  2038. Save the current cursor position into two static variables (cursx,cursy).
  2039. These variables can only be seen within this module.
  2040.  
  2041. -------------------------------------------------------------------------------
  2042. Function        WNsavedos
  2043. Prototype in    wn.h
  2044. Module            wn
  2045. Library            wnl
  2046.  
  2047. void    WNsavedos(void)
  2048.  
  2049. Save the current DOS screen. Used in WNinit.
  2050.  
  2051. -------------------------------------------------------------------------------
  2052. Function        WNselect
  2053. Prototype in    wn.h
  2054. Module            wn
  2055. Library            wnl
  2056.  
  2057. WNwin    *WNselect(WNwin *win)
  2058.  
  2059. Make the window pointed to by 'w' the current window.
  2060.  
  2061. -------------------------------------------------------------------------------
  2062. Function        WNvline
  2063. Prototype in    wn.h
  2064. Module            wn
  2065. Library            wnl
  2066.  
  2067. void    WNvline(int t,int b,int x,int f)
  2068.  
  2069. Draws a vertical line (single or double) from x,t to x,b.
  2070.  
  2071. Parameters
  2072.     t    The top y-position of the line.
  2073.     b    The bottom y-position of the line.
  2074.     x    The x-position of the line.
  2075.     f    0 for a single line, or 1 for a double.
  2076.  
  2077. Returns
  2078.     nothing
  2079.  
  2080. -------------------------------------------------------------------------------
  2081. Function        binary
  2082. Prototype in    misc.h
  2083. Module            misc
  2084. Library            tll
  2085.  
  2086. char    *binary(uint16 val,int digits)
  2087.  
  2088. Decodes a 16-bit integer into a character string up to 16 bytes long
  2089. (plus one byte for the terminating NULL) containing the ASCII
  2090. representation of the integer in binary. 'digits' specifies the number
  2091. of bits to decode. Eg, if 'val' was 25, and 'digits' was 8, the function
  2092. would return a pointer to a string consisting of "00011001". This string
  2093. is a locally declared static variable, and is overwritten with each call.
  2094.  
  2095. Parameters
  2096.     val        The integer to convert.
  2097.     digits    The number of bits to convert.
  2098.  
  2099. Returns
  2100.     A pointer to the converted string.
  2101.  
  2102. -------------------------------------------------------------------------------
  2103. Function        chkdrive
  2104. Prototype in    disk.h
  2105. Module            disk
  2106. Library            tll
  2107.  
  2108. int        chkdrive(int drive)
  2109.  
  2110. Check to see if the specified drive is valid. Works for all floppy
  2111. disks, hard disks, and network drives.
  2112.  
  2113. Thanks to marty@Shiva.COM (Marty Del Vecchio) for the idea, and
  2114. valley@gsbsun.uchicago.edu (Doug Dougherty) for the code, on which
  2115. this implementation is based.
  2116.  
  2117. Parameters
  2118.     drive    The drive to check (Range 'a'-'z' or 'A'-'Z').
  2119.             Eg, chkdrive('A') or chkdrive('a') to see if drive 'A:'
  2120.             is valid.
  2121.  
  2122. Returns
  2123.     TRUE if the drive is valid, or FALSE if it isn't.
  2124.  
  2125. -------------------------------------------------------------------------------
  2126. Function        datelong
  2127. Prototype in    date.h
  2128. Module            date
  2129. Library            tll
  2130.  
  2131. long    datelong(datest *d)
  2132.  
  2133. Given a pointer to a 'datest' structure, return the Day number of the
  2134. specified date(1-11967900). The datest structure contains the
  2135. year(1-32767), the month(1-12), and the day(1-31).
  2136.  
  2137. Day 1, Month 1, Year 1 is Day number 1.
  2138.  
  2139. -------------------------------------------------------------------------------
  2140. Function        daynam
  2141. Prototype in    date.h
  2142. Module            date
  2143. Library            tll
  2144.  
  2145. char    *daynam(int d)
  2146.  
  2147. Returns a pointer to the 3-letter day name corresponding to the
  2148. day number parsed. Eg, 1 returns "Sun".
  2149.  
  2150. -------------------------------------------------------------------------------
  2151. Function        dayname
  2152. Prototype in    date.h
  2153. Module            date
  2154. Library            tll
  2155.  
  2156. char    *dayname(int d)
  2157.  
  2158. Returns a pointer to the full day name corresponding to the
  2159. day number parsed. Eg, 1 returns "Sunday".
  2160.  
  2161. -------------------------------------------------------------------------------
  2162. Function        daysuff
  2163. Prototype in    date.h
  2164. Module            date
  2165. Library            tll
  2166.  
  2167. char    *daysuff(int d)
  2168.  
  2169. Returns a pointer to the 2-letter suffix which should be appended to the
  2170. day number parsed. Eg, 21 returns "st".
  2171.  
  2172. -------------------------------------------------------------------------------
  2173. Function        delenvp
  2174. Prototype in    env.h
  2175. Module            env
  2176. Library            tll
  2177.  
  2178. int        delenvp(char *var)
  2179.  
  2180. Delete a variable from the root environment.
  2181.  
  2182. Parameters
  2183.     var        The variable to delete.
  2184.  
  2185. Returns
  2186.     TRUE if the variable was deleted, FALSE if it wasn't found.
  2187.  
  2188. -------------------------------------------------------------------------------
  2189. Function        dice
  2190. Prototype in    random.h
  2191. Module            random
  2192. Library            tll
  2193.  
  2194. int        dice(int n,int d)
  2195.  
  2196. Rolls a 'd' sided dice 'n' times, summing the results. Eg, dice(4,6)
  2197. simulates the rolling of 4 6-sided dice, returning a number from 4 to 24.
  2198.  
  2199. Parameters
  2200.     n        The number of dice to roll.
  2201.     d        The number of sides on each dice.
  2202.  
  2203. Returns
  2204.     The sum of the result of the rolls.
  2205.  
  2206. -------------------------------------------------------------------------------
  2207. Function        endtrap
  2208. Prototype in    misc.h
  2209. Module            misc
  2210. Library            tll
  2211.  
  2212. void    endtrap(void)
  2213.  
  2214. Turns off BREAK key checking. See trapbreak.
  2215.  
  2216. Parameters
  2217.     none
  2218.  
  2219. Returns
  2220.     nothing
  2221.  
  2222. -------------------------------------------------------------------------------
  2223. Function        farcmp
  2224. Prototype in    far.h
  2225. Module            far
  2226. Library            tll
  2227.  
  2228. int        farcmp(char far *s1,char far *s2,int n)
  2229.  
  2230. Compares two "far" strings. Returns TRUE or FALSE rather than a proper
  2231. comparison. This will be fixed in a future version. I'm not even sure this
  2232. is the right way to implement these functions, as it makes the libraries
  2233. dependent on this one (any that use these functions), and I'd like to keep
  2234. them completely independent.
  2235.  
  2236. Parameters
  2237.     s1        The first string to compare.
  2238.     s2        The second string to compare.
  2239.     n        The maximum number of bytes to compare.
  2240.  
  2241. Returns
  2242.     TRUE if the strings are identical, or FALSE if they aren't.
  2243.  
  2244. -------------------------------------------------------------------------------
  2245. Function        farmov
  2246. Prototype in    far.h
  2247. Module            far
  2248. Library            tll
  2249.  
  2250. void    farmov(char far *s1,char far *s2,int n)
  2251.  
  2252. Copies one "far" string to another. See 'farcmp' for more info.
  2253.  
  2254. Parameters
  2255.     s1        The string to copy from.
  2256.     s2        The string to copy to.
  2257.     n        The maximum number of bytes to copy.
  2258.  
  2259. Returns
  2260.     nothing
  2261.  
  2262. -------------------------------------------------------------------------------
  2263. Function        fndenvp
  2264. Prototype in    env.h
  2265. Module            env
  2266. Library            tll
  2267.  
  2268. void    fndenvp(void)
  2269.  
  2270. Locate the root environment, and set some variables for use by other
  2271. functions in this module.
  2272.  
  2273. Parameters
  2274.     none
  2275.  
  2276. Returns
  2277.     nothing
  2278.  
  2279. -------------------------------------------------------------------------------
  2280. Function        getarg
  2281. Prototype in    arg.h
  2282. Module            arg
  2283. Library            tll
  2284.  
  2285. char    *getarg(void)
  2286.  
  2287. Gets succesive arguments from the command line. If called before a 'getopt'
  2288. will get all arguments, including options. However, it is designed to be
  2289. used after a 'getopt'. Each call to getarg will return the next argument
  2290. on the command line.
  2291.  
  2292. Parameters
  2293.     none
  2294.  
  2295. Returns
  2296.     A pointer to the next command line argument, or NULL if there are none.
  2297.  
  2298. -------------------------------------------------------------------------------
  2299. Function        getopt
  2300. Prototype in    arg.h
  2301. Module            arg
  2302. Library            tll
  2303.  
  2304. void    getopt(char *opts,...)
  2305.  
  2306. Interprets command line arguments according to the rules specified in
  2307. the string 'opts'. It uses the external variable '_argv', which is a
  2308. pointer to the command line argument array, to get the command line
  2309. arguments. The string 'opts' consists of a sequence of alphanumeric
  2310. characters, each one optionally followed by a non-alphanumeric character.
  2311. Each alphanumeric specifies a valid option. If it is followed by a colon,
  2312. the option may have an argument. If it is followed by any other non-
  2313. alphanumeric, the option may still have an argument, but the argument will
  2314. be appended to the storage area for that option, with the specified
  2315. non-alphanumeric character as a seperator.
  2316.  
  2317. The string 'opts' should be followed by a series of pointers to locations
  2318. to hold the data. There should always be exactly the same number of
  2319. pointers as characters in 'opts'. Each alphanumeric character should have
  2320. a corresponding pointer to an integer to hold the number of times that
  2321. option was specified on the command line, and each non-alphanumeric
  2322. character should have a pointer to a character array to hold the argument
  2323. following the option (if any). Any of the pointers may be NULL, indicating
  2324. that the corresponding value should not be stored.
  2325.  
  2326. Getopt makes any found argument or option into a null-string. Thus, getarg
  2327. can be called after getopt to return any remaining arguments.
  2328.  
  2329. An example of use would be good...
  2330.  
  2331. void main(void)
  2332. {
  2333.     int        opt_a,opt_b;
  2334.     char    arg_c[81];
  2335.     char    *s;
  2336.  
  2337.     getopt("ab:c;",&opt_a,&opt_b,NULL,NULL,arg_c);
  2338.  
  2339.     printf("Option a was entered %d times\r\n",opt_a);
  2340.     printf("Option b was entered %d times\r\n",opt_b);
  2341.     printf("Option c had arguments %s\r\n",arg_c);
  2342.  
  2343.     while (s = getarg())
  2344.         printf("Argument = %s\r\n");
  2345. }
  2346.  
  2347. This program would accept and count the number of occurrences of '-a' on
  2348. the command line, and the same for '-b'. Any arguments following a '-b'
  2349. would be ignored. Each occurrence of '-c' would have it's argument appended
  2350. to 'arg_c', with ';' as the seperator character.
  2351.  
  2352. Parameters
  2353.     opts    The specification string
  2354.     ...        A list of pointers to either integers or character strings.
  2355.  
  2356. Returns
  2357.     nothing
  2358.  
  2359. -------------------------------------------------------------------------------
  2360. Function        getshftstate
  2361. Prototype in    misc.h
  2362. Module            misc
  2363. Library            tll
  2364.  
  2365. int        getshftstate(void)
  2366.  
  2367. This function returns the current state of the shift keys. At the moment
  2368. it merely reflects what BIOS thinks they are. If you have not been
  2369. chaining to the BIOS keyboard handler (because you have your own installed)
  2370. this function may return incorrect values.
  2371.  
  2372. The following four values are defined in misc.h for use in determining
  2373. whether a given shift key is depressed :
  2374.  
  2375. RSHIFT    0x01
  2376. LSHIFT    0x02
  2377. CTRL    0x04
  2378. ALT        0x08
  2379.  
  2380. To determine if a given key is pressed, AND the result of getshftstate
  2381. with the corresponding value. Eg, (getshftstate() & CTRL) will return
  2382. TRUE if the CTRL key is currently pressed.
  2383.  
  2384. Parameters
  2385.     none
  2386.  
  2387. Returns
  2388.     The current state of the shift keys, as follows :
  2389.     Bit 0    Right Shift Key        (1=pressed)
  2390.     Bit 1    Left Shift Key        (1=pressed)
  2391.     Bit 2    Control Key            (1=pressed)
  2392.     Bit 3    Alt Key                (1=pressed)
  2393.     Bit 4    Scroll-Lock status    (1=on)
  2394.     Bit 5    Num-Lock status        (1=on)
  2395.     Bit 6    Caps-Lock status    (1=on)
  2396.     Bit 7    Insert status        (1=on)
  2397.  
  2398. -------------------------------------------------------------------------------
  2399. Function        kbreset
  2400. Prototype in    misc.h
  2401. Module            misc
  2402. Library            tll
  2403.  
  2404. void    kbreset(void)
  2405.  
  2406. This resets the keyboard after a scan-code has been sent, and sends an
  2407. EOI to the 8259 controller. This function is normally done by the old
  2408. interrupt 9 handler, but if it your handler does not chain to the old
  2409. interrupt handler, then this function must be called before exiting.
  2410.  
  2411. Parameters
  2412.     none
  2413.  
  2414. Returns
  2415.     nothing
  2416.  
  2417. -------------------------------------------------------------------------------
  2418. Function        leapyear
  2419. Prototype in    date.h
  2420. Module            date
  2421. Library            tll
  2422.  
  2423. int        leapyear(int y)
  2424.  
  2425. Given a year(1-32767), return non-zero (TRUE) if it is a leapyear,
  2426. zero (FALSE) if it is not.
  2427. Uses the following rules :
  2428.  
  2429. If a year is evenly divisible by 4, it is a leapyear, unless it is
  2430. evenly divisible by 100 and not 400.
  2431. eg, 0, 4, 8, etc are leapyears.
  2432.     100, 200, 300 are not leapyears.
  2433.     400, 800, 1200, etc are leapyears.
  2434.  
  2435. -------------------------------------------------------------------------------
  2436. Function        locks
  2437. Prototype in    misc.h
  2438. Module            misc
  2439. Library            tll
  2440.  
  2441. uint8    locks(uint8 on,uint8 off)
  2442.  
  2443. Change the status of the num-lock, scroll-lock and caps-lock keys. At this
  2444. stage, this function merely updates the BIOS record. At some point, BIOS
  2445. updates the keyboard leds. I think this is only during keyboard or screen
  2446. I/O. I ran a batch file to call this function repeatedly, and it worked
  2447. while echo was on, but crashed the machine otherwise, so Handle With Care.
  2448.  
  2449. Note that OFF parameters take precedence over ON. Thus,
  2450.  
  2451. locks( L_SCR|L_NUM , L_NUM|L_CAP )
  2452.  
  2453. will turn the Scroll-lock key on, and both the Num-lock and Caps-lock
  2454. keys off. Also, since locks returns the current state of the lock keys,
  2455. and locks(0,0) will change nothing, it can be used to determine the
  2456. current state.
  2457.  
  2458. Parameters
  2459.     on        Bitwise OR of the locks to turn on. Eg, L_SCR | L_NUM.
  2460.     off        Bitwise AND of the keys to turn off. Eg, L_NUM | L_CAP.
  2461.  
  2462. Returns
  2463.     The current state of the lock keys.
  2464.  
  2465. -------------------------------------------------------------------------------
  2466. Function        longdate
  2467. Prototype in    date.h
  2468. Module            date
  2469. Library            tll
  2470.  
  2471. datest    *longdate(datest *ds,long d)
  2472.  
  2473. Given a Day number as per function datelong, return the date in the
  2474. variable pointed to by 'ds'.
  2475.  
  2476. -------------------------------------------------------------------------------
  2477. Function        longdow
  2478. Prototype in    date.h
  2479. Module            date
  2480. Library            tll
  2481.  
  2482. int        longdow(long d)
  2483.  
  2484. Given a Day number as per function datelong, return the day of the week
  2485. on that day(1-7). Sunday is the 1st day of the week, Saturday is the 7th.
  2486.  
  2487. -------------------------------------------------------------------------------
  2488. Function        monlen
  2489. Prototype in    date.h
  2490. Module            date
  2491. Library            tll
  2492.  
  2493. int        monlen(int m,int y)
  2494.  
  2495. Given month(1-12) and year(1-32767), return the length of the month.
  2496.     monlen(2,1991) returns 28        (February 1991 has 28 days)
  2497.     monlen(2,1992) returns 29        (February 1992 has 29 days)
  2498.  
  2499. -------------------------------------------------------------------------------
  2500. Function        monsum
  2501. Prototype in    date.h
  2502. Module            date
  2503. Library            tll
  2504.  
  2505. int        monsum(int m,int y)
  2506.  
  2507. Given month(1-12) and year(1-32767), return the number of days within
  2508. the year prior to the first of that month (0-335).
  2509.  
  2510. monsum(1,1991) returns 0        (01/01/1991 is Day 1  of 1991)
  2511. monsum(2,1991) returns 31        (01/02/1991 is Day 32 of 1991)
  2512. monsum(3,1991) returns 59        (01/03/1991 is Day 60 of 1991)
  2513. monsum(3,1992) returns 60        (01/03/1992 is Day 61 of 1992 - leapyear)
  2514.  
  2515. -------------------------------------------------------------------------------
  2516. Function        monthnam
  2517. Prototype in    date.h
  2518. Module            date
  2519. Library            tll
  2520.  
  2521. char    *monthnam(int m)
  2522.  
  2523. Returns a pointer to the 3-letter month name corresponding to the
  2524. month number parsed. Eg, 1 returns "Jan".
  2525.  
  2526. -------------------------------------------------------------------------------
  2527. Function        monthname
  2528. Prototype in    date.h
  2529. Module            date
  2530. Library            tll
  2531.  
  2532. char    *monthname(int m)
  2533.  
  2534. Returns a pointer to the full month name corresponding to the
  2535. month number parsed. Eg, 1 returns "January".
  2536.  
  2537. -------------------------------------------------------------------------------
  2538. Function        mplay
  2539. Prototype in    music.h
  2540. Module            music
  2541. Library            tll
  2542.  
  2543. char    *mplay(char *szName)
  2544.  
  2545.         Polyphonic Music Player v1.2
  2546. Written in DeSmet C and placed in the public domain
  2547.         by:    Mike Talvola
  2548.             Agoura Hills, CA
  2549.  
  2550. Permission is hereby granted to copy, modify, and
  2551. otherwise use this program except for profit.
  2552.  
  2553. Inspired by "Polyphonic Music on the IBM PC"
  2554.     by:    Steve Muenter
  2555.  
  2556. This function uses tri() to play a tune stored in a file. The file has a
  2557. default extension of ".POL", and should contain a series of integers
  2558. seperated by blanks or newlines. Each of the integers should be in the
  2559. format specified for tri().
  2560.  
  2561. Parameters
  2562.     szName    A pointer to the filename containing the data to play.
  2563.  
  2564. Returns
  2565.     A pointer to the name of the file played.
  2566.  
  2567. -------------------------------------------------------------------------------
  2568. Function        play
  2569. Prototype in    music.h
  2570. Module            music
  2571. Library            tll
  2572.  
  2573. void    play(char *s)
  2574.  
  2575. Plays notes from the character string s. S should contain a sequence of
  2576. commands, optionally followed by a single digit argument, as follows :
  2577.  
  2578. Command        Argument    Function
  2579. A-G            1-9            Play the note, set the length for this note only
  2580.                         if the argument is present.
  2581. T            0-9            Set the tempo from 0 (fastest) to 9 (slowest).
  2582. L            1-9            Set the default note length from 1 (full note) to
  2583.                         9 (1/256th note).
  2584. O            0-9            Set the octave from 0 (lowest) to 9 (highest).
  2585. @            filename    Continue getting commands from the specified file.
  2586.                         Unless this is the last command in the string, the
  2587.                         argument should be terminated by another '@'. The
  2588.                         file can contain multiple lines, and can contain
  2589.                         another '@' command. '@'s can be nested until you
  2590.                         run out of memory.
  2591.  
  2592. Parameters
  2593.     s        A pointer to the string holding the commands to play.
  2594.  
  2595. Returns
  2596.     Nothing
  2597.  
  2598. -------------------------------------------------------------------------------
  2599. Function        randomise
  2600. Prototype in    random.h
  2601. Module            random
  2602. Library            tll
  2603.  
  2604. void    randomise(void)
  2605.  
  2606. This function is only here to correct a spelling mistake in Turbo-C
  2607. (if you're Aussie it's a spelling mistake anyway). I got sick of having
  2608. to correct myself.
  2609.  
  2610. All it does is seed the random number generator from the PC's clock.
  2611.  
  2612. Parameters
  2613.     none
  2614.  
  2615. Returns
  2616.     nothing
  2617.  
  2618. -------------------------------------------------------------------------------
  2619. Function        readcmos
  2620. Prototype in    cmos.h
  2621. Module            cmos
  2622. Library            tll
  2623.  
  2624. int        readcmos(int port)
  2625.  
  2626. Read a CMOS location, waiting for a valid RTC value before returning if
  2627. the location is an RTC location.
  2628.  
  2629. Parameters
  2630.     port    The location to read, range from 0x00 to 0xff.
  2631.  
  2632. Returns
  2633.     The value at that location, range from 0x00 to 0xff.
  2634.  
  2635. -------------------------------------------------------------------------------
  2636. Function        setenvp
  2637. Prototype in    env.h
  2638. Module            env
  2639. Library            tll
  2640.  
  2641. int        setenvp(char *var,char *val)
  2642.  
  2643. Set a variable in the root environment. If the variable does not exist,
  2644. create it. If it does, replace it.
  2645.  
  2646. Parameters
  2647.     var        The variable to set.
  2648.     val        The value to give it.
  2649.  
  2650. Returns
  2651.     TRUE if the variable could be set, FALSE if there wasn't enough room.
  2652.  
  2653. -------------------------------------------------------------------------------
  2654. Function        settimer
  2655. Prototype in    misc.h
  2656. Module            misc
  2657. Library            tll
  2658.  
  2659. void    settimer(ulong hz)
  2660.  
  2661. Theoretically this function changes the PC's 18.2hz clock pulses to any
  2662. desired frequency, but as far as I can tell, it doesn't seem to work.
  2663. Maybe the next version.
  2664.  
  2665. Parameters
  2666.     hz        The desired clock frequency.
  2667.  
  2668. Returns
  2669.     nothing
  2670.  
  2671. -------------------------------------------------------------------------------
  2672. Function        trapbreak
  2673. Prototype in    misc.h
  2674. Module            misc
  2675. Library            tll
  2676.  
  2677. void    trapbreak(void)
  2678.  
  2679. This detects all the various BREAK key combinations and ignores them.
  2680. Anything else is passed through to the normal keyboard handler. The
  2681. key combinations which are ignored are as follows :
  2682.  
  2683. CTRL-2
  2684. CTRL-ScrlLock
  2685. CTRL-C
  2686. CTRL-ALT-Delete
  2687. ALT-Keypad0 to Keypad9
  2688.  
  2689. Note this last one. The user can normally use the keypad keys with <ALT>
  2690. to generate any ASCII code. If they generate ASCII 3, this is interpreted
  2691. as a BREAK. To prevent this, I disable the <ALT>keypad function completely.
  2692. This was infinitely easier than trying to interfere with the BIOS routine
  2693. which accumulates the <ALT>keypad keystrokes and delivers the ASCII value.
  2694.  
  2695. Also, CTRL-ALT-Delete is trapped. I figure if you don't want the user
  2696. breaking out of your program, you don't want him rebooting your machine
  2697. either. An interesting note is that we can never take away the power
  2698. switch, so if the idiot really wants to, he can always stuff up his data
  2699. one way or another. However, the purpose of this routine is simply to
  2700. make sure he doesn't do it accidentally.
  2701.  
  2702. This function is one of three. The other two are endtrap and traphandler.
  2703. Endtrap is called to turn BREAK key trapping off. Traphandler should not
  2704. be called by the programmer. It is the interrupt handler.
  2705.  
  2706. Parameters
  2707.     none
  2708.  
  2709. Returns
  2710.     nothing
  2711.  
  2712. -------------------------------------------------------------------------------
  2713. Function        traphandler
  2714. Prototype in    misc.h
  2715. Module            misc
  2716. Library            tll
  2717.  
  2718. void    interrupt traphandler(void)
  2719.  
  2720. The interrupt handler for BREAK key checking. See trapbreak.
  2721. Should not be called by the programmer.
  2722.  
  2723. Parameters
  2724.     none
  2725.  
  2726. Returns
  2727.     nothing
  2728.  
  2729. -------------------------------------------------------------------------------
  2730. Function        tri
  2731. Prototype in    music.h
  2732. Module            music
  2733. Library            tll
  2734.  
  2735. void    tri(short *tune)
  2736.  
  2737. play 3-voice music
  2738.  
  2739. Copyright (C) A.Bogatyrev (abs)
  2740.                 Moscow  1990.
  2741. Program is placed in the public domain by: ABS.
  2742. Permission is hereby granted to copy, modify,
  2743. and otherwise use this program except for profit.
  2744. .................................................
  2745. Modified by:    Kevin Spencer
  2746.                 17 Winchelsea Rd,
  2747.                 NOLLAMARA  WA  6061
  2748.  
  2749. Takes an array of 'short', and plays it. Each element in the array must
  2750. be at least 16 bits long. The highest 3 bits represent the Command, and
  2751. the lowest 13 bits represent the Value. The commands are as follows :
  2752.  
  2753. 000        End-Of-Tune
  2754. 001        Delay for Value, then play Voices 1,2 & 3
  2755. 010        Change Tempo to Value
  2756. 011        Ignore this Value
  2757. 100        Set Pitch for Voice 1
  2758. 101        Set Pitch for Voice 2
  2759. 110        Set Pitch for Voice 3
  2760. 111        Set Pitch for Voice 3
  2761.  
  2762. Note that this is only my best guess at how this thing really works.
  2763. Take it with a pinch of salt.
  2764.  
  2765. Parameters
  2766.     tune    A pointer to the array described above.
  2767.  
  2768. Returns
  2769.     Nothing
  2770.  
  2771. -------------------------------------------------------------------------------
  2772. Function        updateclock
  2773. Prototype in    cmos.h
  2774. Module            cmos
  2775. Library            tll
  2776.  
  2777. void    updateclock(void)
  2778.  
  2779. Update DOS' date/time using the value in the CMOS Real-Time-Clock.
  2780.  
  2781. Parameters
  2782.     none
  2783.  
  2784. Returns
  2785.     nothing
  2786.  
  2787. -------------------------------------------------------------------------------
  2788.